Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add, refactor, and reformat discourse docs feat. charmcraft #2010

Merged
merged 25 commits into from
Jan 14, 2025

Conversation

tmihoc
Copy link
Member

@tmihoc tmihoc commented Nov 29, 2024

This PR adds all the juju.is/docs content featuring Charmcraft.

The content was originally formatted for Discourse; this PR reformats it to serve the RTD project the docs are destined for.

The content was also originally entangled with Ops content; this PR significantly refactors -- as well as clarifies and tries to complete -- everything to serve the stand-alone Charmcraft docs set it is destined for.

Issues that should be fixed in subsequent PRs:

  • Everywhere: (1) (a) Links to juju.is will work, as even after moving docs out of there we'll have redirects; however, they should be updated. (b) Links to ops docs are empty -- they reference content I'm planning to move there post-refactoring; once we have them in place, which should be in the next few days and pre-official-Charmcraft-RTD-launch, we should add them in Charmcraft docs.
  • Tutorial: The tutorial should also be offered in the "regular" flavor, that is, for apps that are not 12-factor. That flavor should also feature the publish step. (See, e.g., our old Kubernetes tutorial, which includes https://juju.is/docs/sdk/publish-your-charm-on-charmhub . PS If the Charmcraft tutorial starts featuring this, as it should, the old Kubernetes tutorial, which will be moved to the stand-alone Ops docs, can focus on just development, which is what Ops is really all about.)
  • How-to guides: While this PR surfaces a lot more of Charmcraft and arguably a lot more clearly, there are still corners with cobwebs or gaps. These include: (1) Manage charms (12-factor app) -- I think this doc should be incorporated into the main Manage charms doc, which could have tabs for "regular', "django", etc. (This would align with plans for the juju.is/docs entrypoint into the "federated docs"). (2) The Manage parts doc, which is full of "TBA" -- i.e., has gaps. (3) The docs in "Misc", which are not well integrated with everything else here. (4) Maybe the Manage bundles doc, which doesn't by far tell the full story; given that we're phasing bundles out, it's also perhaps fine not to worry about this too much. (5) Commands analyse and test are not featured in any how-to guide.
  • Reference: (1) The autogenerated charmcraft CLI command reference docs should have anchors on the template command-charmcraft-x and titles on the template "Command charmcraft x. This will not better align with existing practices in the Juju world but also results in more clarity when linking to the page using {ref}...`` (2) The various file reference docs should be as much as possible autogenerated from source (likely the source will have to be updated first) -- at the very least, file charmcraft.yaml. They may also need further clean-up. (3) The part docs are a bit of a mess. We should move any relevant content to the part docs, then link up to that and only keep in Charmcraft the material specific to Charmcraft docs, and then revisit that material as well to streamline it as much as possible (e.g., currently the dump plugin is documented in 3 places). (4) Charmcraft analyzers and linters -- this gives details on pack and analyse but it's not clear in what way it's useful to the reader, so we need to rethink.
  • Explanation: We have nothing there. I didn't delete that section as I think there is potentially a topic we could have there -- e.g., Charmcraft in the bigger context of Starcraft (a clarification of the general design philosophy there and trends, maybe).

PS Some docs may have a Contributors list on the bottom, listing the Discourse handles of the contributors to date. We'll want to rethink how we do that.

@medubelko medubelko self-requested a review November 29, 2024 17:41
@lengau
Copy link
Collaborator

lengau commented Nov 29, 2024

We can ignore the test failures, but the linter that's failing is codespell and is related to these changes: https://github.com/canonical/charmcraft/actions/runs/12084317065/job/33699249108?pr=2010#step:6:637

docs/common/craft-parts Outdated Show resolved Hide resolved
@tmihoc tmihoc force-pushed the rtd-docs branch 2 times, most recently from b86dd66 to b69eb9d Compare December 2, 2024 15:16
@tmihoc
Copy link
Member Author

tmihoc commented Dec 2, 2024

We can ignore the test failures, but the linter that's failing is codespell and is related to these changes: https://github.com/canonical/charmcraft/actions/runs/12084317065/job/33699249108?pr=2010#step:6:637

I think I've addressed all of these now.

Copy link
Collaborator

@lengau lengau left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, thanks!

@lengau
Copy link
Collaborator

lengau commented Dec 3, 2024

Hey, so pandoc can convert these markdown files to rst: pandoc -s <file>.md -o <file>.rst

@medubelko
Copy link
Contributor

medubelko commented Dec 12, 2024

The following pages have extensive maintenance planned post-migration, so they don't need detailed review:

  • reference/extensions/charmcraft-extension-django-framework
  • reference/extensions/charmcraft-extension-fastapi-framework
  • reference/extensions/charmcraft-extension-flask-framework
  • reference/extensions/charmcraft-extension-go-framework
  • howto/manage-12-factor-app-charms
  • tutorial/write-your-first-kubernetes-charm-for-a-django-app
  • tutorial/write-your-first-kubernetes-charm-for-a-fastapi-app
  • tutorial/write-your-first-kubernetes-charm-for-a-go-app

lengau added a commit that referenced this pull request Dec 17, 2024
I'm breaking down the content from PR #2010 into smaller chunks.

This is "How to manage 12-factor app charms" converted to RST:
https://github.com/canonical/charmcraft/blob/737976c943a601adccd883ffa6a276bce625c9a1/docs/howto/manage-12-factor-app-charms.md

The main differences from the Markdown version:

- Uses tabs instead of dropdowns (matching the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/latest/how-to/build-a-12-factor-app-rock/)
- "See also" blocks are added as cards
lengau added a commit that referenced this pull request Dec 17, 2024
I'm breaking down the content from PR #2010 into smaller chunks.

This is "How to manage 12-factor app charms" converted to RST:
https://github.com/canonical/charmcraft/blob/737976c943a601adccd883ffa6a276bce625c9a1/docs/howto/manage-12-factor-app-charms.md

The main differences from the Markdown version:

- Uses tabs instead of dropdowns (matching the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/latest/how-to/build-a-12-factor-app-rock/)
- "See also" blocks are added as cards
lengau added a commit that referenced this pull request Dec 17, 2024
I'm breaking down the content from PR #2010 into smaller chunks.

This is "How to manage 12-factor app charms" converted to RST:
https://github.com/canonical/charmcraft/blob/737976c943a601adccd883ffa6a276bce625c9a1/docs/howto/manage-12-factor-app-charms.md

The main differences from the Markdown version:

- Uses tabs instead of dropdowns (matching the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/latest/how-to/build-a-12-factor-app-rock/)
- "See also" blocks are added as cards
lengau added a commit that referenced this pull request Dec 17, 2024
This reorganises the part reference in line with #2010
Copy link
Contributor

@medubelko medubelko left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving without review. If we merge this, we can resolve any code issues during separate RST conversion tasks.

lengau added a commit that referenced this pull request Dec 17, 2024
I'm breaking down the content from PR #2010 into smaller chunks.

This is "How to manage 12-factor app charms" converted to RST:
https://github.com/canonical/charmcraft/blob/737976c943a601adccd883ffa6a276bce625c9a1/docs/howto/manage-12-factor-app-charms.md

The main differences from the Markdown version:

- Uses tabs instead of dropdowns (matching the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/latest/how-to/build-a-12-factor-app-rock/)
- "See also" blocks are added as cards
@lengau lengau requested a review from sergiusens as a code owner December 19, 2024 15:29
docs/tutorial/index.rst Outdated Show resolved Hide resolved
@sergiusens
Copy link
Collaborator

We've decided to merge this this week, with the caveat that we will make changes to the structure which has the potential to break links

Copy link
Contributor

@medubelko medubelko left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left comments for the files you requested.

docs/reference/files/file-charmcraft-yaml.rst Outdated Show resolved Hide resolved
docs/reference/files/file-charmcraft-yaml.rst Outdated Show resolved Hide resolved
docs/reference/files/file-charmcraft-yaml.rst Outdated Show resolved Hide resolved
docs/reference/files/file-charmcraft-yaml.rst Outdated Show resolved Hide resolved
docs/reference/files/file-charmcraft-yaml.rst Outdated Show resolved Hide resolved
docs/reference/files/file-charmcraft-yaml.rst Outdated Show resolved Hide resolved
docs/reference/files/file-libname-py.md Outdated Show resolved Hide resolved
docs/reference/files/file-libname-py.md Outdated Show resolved Hide resolved
docs/reference/files/file-libname-py.md Outdated Show resolved Hide resolved
docs/tutorial/index.rst Outdated Show resolved Hide resolved
Co-authored-by: Michael DuBelko <michael.dubelko@gmail.com>
@medubelko medubelko requested a review from lengau January 14, 2025 02:25
@medubelko
Copy link
Contributor

@lengau I spent a bit of extra time on the clean up. Should be good to go. This includes part of the fix from #2070. I don't think a complete re-review is needed – a look at conf.py and the project files should be enough.

@lengau lengau merged commit a1a3d4b into canonical:main Jan 14, 2025
19 of 20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants